chillJS - tutorials: element types

Container element

This is the most important element type. Only ContainerElement can hold other elements. Every Layer has a main container by default, called "body". There are more ways to access it:

var body = layer.body;
// or
var body = layer.getElementByID('body');

However you don't have to get the body in order to add elements to it. You only need to provide the id in the Layer.add method, which is body by default. Let's see, how to add elements to other containers.

// adds a container element to layer.body
var myContainer = layer.insert('Container', ['myContainer', {
	x: 50,
	y: 50,
	background: 'orange'
}]);

var text = layer.create('Text', {
	text: 'flowing text\ninside the orange container',
	flow: 'horizontal'
});

layer.background = '#abcdef';
layer.add(text, 'myContainer'); // notice the second param

Text element

TextElement is for displaying text on the Layer. It extends Element, so you can also set much more (common)properties, such as Element.background. Some of the TextElement properties might be familiar from HTML element styling.

You can set the text of the element with TextElement.text. The width is "auto" by default, which means the element horizontal size will be measured (width of longest row). The height is also "auto", the vertical size will be calculated (number of lines multiplied by the measured line height). The TextElement.lineHeight is default to "auto" (100%). It could be numeric or percentage (relative to TextElement.fontSize) too. TextElement.textColor specifies the color of the text. The TextElement.fontWeight defines the thickness of the letters ("bold" or "normal"), TextElement.fontStyle can be "italic" or "normal". The TextElement.textIndent property specifies how much horizontal space should be left before the beginning of the first line of the text. The TextElement.textAlign property describes how the text is aligned in its rendering box. TextElement.textDecoration (default to "none") is used to set the text formatting to "underline", "overline" or "line-through". The TextElement.textTransform property specifies how to capitalize an element's text. It can be used to make text appear in all-uppercase ("uppercase"), all-lowercase ("lowercase") or with each word capitalized ("capitalize"). The TextElement.fontFamily property lets you specify a font for the text. TextElement.letterSpacing specifies the spacing behavior between the characters. It's a numeric property and indicates how many spaces should be between the words.

var text = layer.create('Text', {
	text: 'my Text\nsecond row\n\nnotice the empty line',
	width: '100%',
	textAlign: 'center',
	textColor: '#ff0000',
	fontWeight: 'bold',
	fontStyle: 'italic',
	lineHeight: '150%'
});

Polygon element

PolygonElement is not instantiatable, but extensible. It extends the Element. It has at least two PolygonElement.vertices. Every vertex is an object, with "x" and "y" properties. These are defined in the extended elements.

PolygonElement.fill specifies the color to use as background inside the shape. It's default to empty string (""), which means transparent.

PolygonElement.strokeWidth sets the thickness of the lines. You also can provide color for lines with PolygonElement.strokeColor.

Line element

LineElement extends PolygonElement. The width and height are a bit tricky here, because LineElement is also represented in a box (like other elements, you can set its background color, or add border to it). The line goes from the top left corner to bottom right. It's vertices are at [0, 0] and [1, 1]. If you want a horizontal line, the height of the line must be 0, for vertical line, set the width to 0. You can also rotate it with Element.angle.

var line = layer.create('Line', {
	x: 50,
	y: 30,
	width: 250,
	strokeWidth: 10
});

Triangle element

TriangleElement extends PolygonElement. Vertices are at [0.5, 0], [1, 1], [0, 1].

var triangle = layer.create('Triangle', {
	width: 50,
	height: 80,
	fill: 'lime'
});

Rectangle element

RectangleElement extends PolygonElement. Vertices are at [0, 0], [1, 0], [1, 1], [0, 1].

var rectangle = layer.create('Rectangle', {
	x: 100,
	y: 100,
	width: 50,
	height: 80,
	angle: 45
});

Pentagon element

PentagonElement extends PolygonElement. Vertices are at [0.5, 0], [1, 0.4], [0.8, 1], [0.2, 1], [0, 0.4].

var pentagon = layer.create('Pentagon', {
	width: 80,
	height: 80
});

Hexagon element

HexagonElement extends PolygonElement. Vertices are at [0.25, 0], [0.75, 0], [1, 0.5], [0.75, 1], [0.25, 1], [0, 0.5].

var hexagon = layer.create('Hexagon', {
	x: '50%',
	y: '50%',
	offsetX: '-50%',
	offsetY: '-50%',
	width: '25%',
	height: '25%',
	fill: 'purple'
});

Star element

StarElement extends PolygonElement. Vertices are at [0, 1], [0.5, 0], [1, 1], [0, 0.3], [1, 0.3].

var star = layer.create('Star', {
	width: '100%',
	height: '100%',
	fill: 'white'
});

Circle element

CircleElement extends Element. The "x" and "y" properties defines the top left corner, not the center of the circle. If you would like othervise, you can use the Element.offsetX and Element.offsetY properties. The CircleElement.r property indicates the radius of the element. You can set its color with the CircleElement.fill, the line width and color with the CircleElement.strokeWidth and CircleElement.strokeColor properties, just like a PolygonElement.

var circle = layer.create('Circle', {
	x: '100%',
	offsetX: '-50%',
	offsetY: '-50%',
	r: 200,
	fill: 'rgb(100, 100, 255)'
});

Ellipse element

EllipseElement extends Element. It's very similar to the CircleElement, only it's uses the "width" and "height" properties in order to determine the size of itself.

var ellipse = layer.create('Ellipse', {
	width: 'fit',
	height: 'fit',
	fill: 'red',
	strokeWidth: 30,
	strokeColor: 'blue'
});

Image element

ImageElement extends Element. It displays an image loaded from a given source. The ImageElement.src property can be a path, or an identifier to a preloaded image. You can preload images with Scene.preload. If you've given an id, you can use it as an src with a hash mark ("#") character at the beginning:

scene.preload('./images/', {
	Image: ['@150x200.jpg as myImage'] // the "@" character replaced to the base path: "./images/"
});

var image = layer.create('Image', {
	src: '#myImage' // "#" character required
});

If you don't want to preload it, you can simply use a path:

var image = layer.create('Image', {
	src: 'images/150x200.jpg'
});

The width and height properties of the ImageElement are "auto" by default, which means it will use the size of the source. The ImageElement.sourceX and ImageElement.sourceY properties are indicates the top left corner of the sub-rectangle of the source image to draw. The ImageElement.sourceWidth and ImageElement.sourceHeight are the width and height of the sub-rectangle of the source image to draw. These properties can be numeric or percentage (relative to the source image).

var image = layer.create('Image', {
	sourceX: 50,
	sourceY: '50%',
	sourceWidth: '50%',
	sourceHeight: 50,
	src: 'images/100x100.png'
});

SpriteSheet element

SpriteSheetElement extends Element. It's used for animating images. The SpriteSheetElement.src works the same way as ImageElement.src. The SpriteSheetElement.sourceX and SpriteSheetElement.sourceY also the same, however SpriteSheetElement.frameWidth and SpriteSheetElement.frameHeight properties are new here. These are indicates the size of each frame from the source image. The SpriteSheetElement.frameRate is used for add latency between the frames. You can add multiple animations to the SpriteSheetElement like "stand", "walk" or "run", with SpriteSheetElement.addAnimation. The first parameter is the id of the animation, the secong is an object, where you can edit the frames or direction of the animation.

var sprite = layer.create('SpriteSheet', {
	frameWidth: 80,
	frameHeight: 80,
	src: 'images/sprite.png',
	setFrames: [4],
	addAnimation: [['default', {
		frames: [0, 1, 2, 3],
		frameRate: 20
	}]]
});

Abstract element

You cannot add AbstractElement to the Scene. This type is providing initial values and implementations of behavior. You create an AbstractElement, then instantiate it. The Layer.create method checks the first character in the element type param. If it's a hash mark (#), then looks for abstract element by the given id. Let's see an example.

Chill.createAbstractElement('Rect-150x200', 'Rectangle', {
	width: 150,
	height: 200,
	flow: 'horizontal'
});

['red', 'blue', 'green'].forEach(function(color) {
	layer.insert('#Rect-150x200', { fill: color });
});